Overview

Composer is a simple but powerful CMS based on [Pandoc], [Bootstrap] and [GNU Make]. It is a document and website build system that processes directories or individual files in [Markdown] format.

Traditionally, CMS stands for Content Management System. Composer is designed to be a Content Make System. Written content is vastly easier to manage as plain text, which can be crafted with simple editors and tracked with revision control. However, professional documentation, publications, and websites require formatting that is dynamic and feature-rich.

[Pandoc] is an extremely powerful document conversion tool, and is a widely used standard for processing [Markdown] into other formats. While it has reasonable defaults, there are a large number of options, and additional tools are required for some formats and features.

Composer consolidates all the necessary components, simplifies the options, and prettifies the output formats, all in one place. It also serves as a build system, so that large repositories can be managed as documentation archives or published as [Bootstrap Websites].

Quick Start

Use make help to get started:

make [-f .../Makefile] [variables] <filename>.<extension>
make [-f .../Makefile] [variables] <target>

Fetch the necessary binary components (see Requirements):

make _update-all

Create documents from source [Markdown] files (see Formatting Variables):

make README.html
make Composer-v3.1.Manual.html c_list="README.md LICENSE.md"

Save a persistent configuration (see [Recommended Workflow], [Configuration Settings] and Special Targets):

make template >.composer.mk
$EDITOR .composer.mk
    book-Composer-v3.1.Manual.html: README.md LICENSE.md
make clean
make all

Recursively install and build an entire directory tree (see [Recommended Workflow]):

cd .../documents
mv .../composer .Composer
make -f .Composer/Makefile install-all
make all-all

See help-all for full details and additional targets.

Principles

The guiding principles of Composer:

• All source files in readable plain text
• Professional output, suitable for publication
• Minimal dependencies, and entirely command-line driven
• Separate content and formatting; writing and publishing are independent
• Inheritance and dependencies; global, tree, directory and file overrides
• Fast; both to initiate commands and for processing to complete

Direct support for key document types (see [Document Formatting]):

• [HTML] & [Bootstrap Websites]
• [PDF]
• [EPUB]
• [Reveal.js Presentations]
• [Microsoft Word & PowerPoint]

Requirements

Composer has almost no external dependencies. All needed components are integrated, including [Pandoc]. The repository needs to be initialized with [_update-all] to fetch the [Pandoc] and [YQ] binaries (see [Repository Versions]).

Composer does require a minimal command-line environment based on [GNU] tools, particularly [GNU Make], which is standard for all [GNU/Linux] systems. The [Windows Subsystem for Linux] for Windows and [MacPorts] for macOS both provide suitable environments.

The one large external requirement is [TeX Live], and it can be installed using the package managers of each of the above systems. It is only necessary for creating [PDF] files.

Below are the versions of the components in the repository, and the tested versions of external tools for this iteration of Composer. Use [check] to validate your system.

[Markdown Viewer] is included both for its CSS stylesheets, and for real-time rendering of [Markdown] files as they are being written. To install, follow the instructions in the README.md, and select the appropriate manifest.*.json file for your browser.

The versions of the integrated repositories can be changed, if desired (see [Repository Versions]).

Formatting Variables

• Other [c_type] values will be passed directly to [Pandoc]
• Special values for [c_css]:
  • css_alt ~ Use the alternate default stylesheet
  • 0 ~ Revert to the [Pandoc] default
• Special value 0 for [c_toc] ~ List all headers, and number sections
• Special value 0 for [c_level] ~ Varies by [c_type] (see [help-all])
• An empty [c_margin] value enables individual margins:
  • c_margin_top ~ mt
  • c_margin_bottom ~ mb
  • c_margin_left ~ ml
  • c_margin_right ~ mr

Control Variables

• [MAKEJOBS] ~ c_jobs ~ J
• [COMPOSER_DOCOLOR] ~ c_color ~ C
• [COMPOSER_DEBUGIT] ~ c_debug ~ V
• (makejobs) = empty is disabled / number of threads / 0 is no limit
• (debugit) = empty is disabled / any value enables / 0 is full tracing
• (boolean) = empty is disabled / any value enables

Primary Targets

Special Targets

There are a few targets considered Specials, that have unique properties:

For each of these base names, there are a standard set of actual targets:

Additional Targets

Happy Making!